home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / tstat.doc < prev    next >
Text File  |  1994-02-13  |  6KB  |  143 lines
  1. Tstat v37.10 (C) Copyright 1990-1993 Commodore-Amiga, Inc.  All Rights Reserved
  2. Usage: tstat [CliNum1-n|ExecTaskName|CliCommandName] [NOCTRL] [-tickdelay]
  3. More options: [SHOWSTACK] [SHOWPC] [SHOWHUNK] [SHOWHUNKCODE] [SERIAL|REMOTE]
  4. Use NOCTRL option when redirecting output to a file
  5. Example: tstat Workbench -10
  6.  
  7. Changes:
  8. 37.9  - SERIAL (aka REMOTE) and Segtracker support
  9. 37.10 - Fix to display PC/regs properly for 68EC020
  10.  
  11. TSTAT
  12. =====
  13.  
  14. TSTAT is a tool that allows you to snoop on the activity of other tasks.
  15.  
  16. Tstat prints out information from the specified named task or CLI number's
  17. Task control block, including processor stack frame information containing
  18. the PC and registers the task had when it was last switched out.
  19. Optionally, TSTAT can show the contents of the top of the stack (SHOWSTACK),
  20. the instructions (in hex) at the PC (SHOWPC), and if SegTracker is
  21. running, the seglist/hunk/offset of the PC or an address on the stack
  22. found in a seglist (SHOWHUNK), and a hex dump of 16 longwords starting
  23. with the longword prior to that hunk and offset.
  24.  
  25. Who to Watch
  26. ============
  27.  
  28. The first command arg to TSTAT tells TSTAT who to watch.
  29.  
  30. This can be specified in one of the following ways:
  31.  
  32. - CLI number                Example: TSTAT 4
  33.   TSTAT will watch CLI 4 and all commands that run as part of CLI 4
  34.  
  35. - Exec task name or CLI command name    Example: TSTAT myprogram
  36.   TSTAT will watch any exec task or CLI command named "myprogram",
  37.   waiting for it to appear when no task/command is present with that name.
  38.  
  39. -tickdelay
  40. ==========
  41. TSTAT can be told to loop via the -tickdelay option (Example -10).
  42. When looping, by default, TSTAT will use console escape sequences to
  43. present a non-scrolling updating-in-place display (as long as the CON
  44. window it's in is big enough for ithe TSTAT display).
  45.  
  46. Example: TSTAT myprogram -10
  47.  
  48. REMOTE/SERIAL option
  49. ====================
  50. The new REMOTE option (aka SERIAL) sends the TSTAT output out via kprintf
  51. so the updating display can be watched in a VT100-compatible terminal
  52. package on a remote machine connected via a null modem cable.
  53.  
  54. Example: TSTAT myprogram -10 SERIAL
  55.       or TSTAT myprogram -10 REMOTE
  56.  
  57. NOCTRL
  58. ======
  59. If you would prefer TSTAT's output to have no escape sequences,
  60. use the NOCTRL option.  This is useful when capturing or
  61. redirecting TSTAT's output.
  62.  
  63. Example: TSTAT >ram:capture myprogram -50 NOCTRL
  64.  
  65. SHOWSTACK
  66. =========
  67. Show the top 16 longwords on the stack.  These longwords are displayed
  68. on the @SP lines.
  69.  
  70. SHOWPC
  71. ======
  72. Show the 16 longwords at the PC (usually within exec.library Wait()
  73. unless task was swapped out while READY).  These longwords are
  74. displayed on the @PC lines.
  75.  
  76. SHOWHUNK
  77. ========
  78. Requires SegTracker (distributed with latest Enforcer).
  79. Show the seglist name, hunk, and offset for the first of the
  80. following which is also in a seglist:  PC, OR an address on stack
  81. whose memory location follows a processor JMP or JSR instruction,
  82. OR any address on stack.  Note - TSTAT only serahces back through
  83. 72 longwords on the stack.  If nothing in a seglist is found within
  84. those 72 longwords, TSTAT will report no seglist found.
  85.  
  86. SHOWHUNKCODE
  87. ============
  88. Requires SegTracker (distributed with latest Enforcer).
  89. Does SHOWHUNK (above) plus shows a hex dump of 16 longwords
  90. at the reported seglist/hunk/offset, starting with the longword
  91. before the offset  This may allow you to see the JMP or JSR that
  92. took the task to a Wait().  These longwords are displayed on the
  93. "@HC" lines.
  94.  
  95. Example: TSTAT more -10 SHOWSTCK SHOWPC SHOWHUNKCODE
  96.  
  97. Sample Output
  98. =============
  99.  CLI=13  Taskname=Shell Process  @$5eb470  Type=PROCESS  State=WAIT    
  100.  Sig: Alloc=$0000ffff Wait=$00000100  Recvd=$80000004 Except=$00000000
  101.  Priority= 0   TDNest= 0  IDNest=-1   TCode=$002b63b8  ECode=$00202ee0     
  102.  SP=$004a29a4  tc_SPLower=$004a03c8   tc_SPUpper=$004a2ad8     
  103.  PC=$002009f0  StkSize=10000  StkUse=308 HiUse=308 LastHi=0       
  104.  Chip:910136  Fast:342632  Command: more                   
  105. d0-7:002809ac 000000ff 00000014 00030d40 00000002 0000000c 0017b4c7 005eb4cc 
  106. a0-6:004a2a00 005eb470 005eb4cc 00000000 005eb470 002807ce 00280804 
  107. @SP: 00216856 00000002 0028099a 005eb4cc 00280804 00215ef0 005ed72c 005ed728
  108. @SP: 056d004a 29d00202 02020202 004a29bc 005eb4cc 00000014 00000000 00000000
  109. @PC: 4e75007c 07002f3c 00000008 6000ff2c 48e70030 20780010 2478002c 43fa0096
  110. @PC: 21c90010 21c9002c 224f7000 4e7b0801 08c00000 223c0000 0a094e7b 10024e7a
  111. On stack $49eae0: seglist "more" Hunk $0001 Offset $00000d80
  112. @HC: 4eaeff34 4a80663c 7000223c 00001000 2c780004 4eaefece 0800000c 67d270ff
  113. @HC: 27400044 222b0014 2c79002e be344eae ff344a80 67082f0b 610010b6 584f7000
  114.  
  115.  
  116. Explanation of output
  117. =====================
  118. CLI number (if any)   Exec Taskname   Process Address, Type, and State
  119. Signals: allocated, waiting for, received, exception
  120. Task Priority, Forbid count (TDNest), Disable count (IDNest) \
  121.     task trapcode pointer, task exception code pointer
  122. Stack pointer (SP) adjusted for procesor stack frame; task tc_Upper/Lower
  123. Program counter (PC), Stack size and amount used
  124. Available memory, CLI command name (if any)
  125. Data registers d0-d7
  126. Address registers a0-a6
  127. Optional SHOWSTACK @SP longwords
  128. Optional SHOWPC @PC longwords
  129. Optional SHOWHUNK seglist/hunk/offset, if any
  130. Optional SHOWHUNKCODE @HC longwords
  131.  
  132. Notes
  133. =====
  134. TDNest and IDNest - generally, for both of these, -1 means none in
  135. effect (i.e. no forbids, no disables).  However, currently, when
  136. a Task is on the WAIT list it also has the appearance of having one
  137. Forbid in effect (i.e. TDNest=0).  SO, when you re watching a task
  138. whose State=WAIT, TDNest=0 IDNest=-1 should be correct for a task
  139. that has no Forbids or Disables in effect.  When a task State=READY,
  140. the TDNest and IDnest should both show as -1 if teh task has no
  141. Forbids or Disables in effect.
  142.  
  143.